Proposal: Allow overwriting static utilities that have a namespace #18056

philipp-spiess · 2025-05-16T10:21:37Z

This PR attempts to move static utilities that are overwriteable by a theme value to be a fallback rather than a conflicting implementation. The idea is to allow a theme value to take presedence over that static utility and cause it not to generate.

For example, when overwriting the --radius-full variant, it should ensure that the default rounded-full no longer emits the calc(infinity * 1px) declaration:

expect(
  await compileCss(
    css`
      @theme {
        --radius-full: 99999px;
      }
      @tailwind utilities;
    `,
    ['rounded-full'],
  ),
).toMatchInlineSnapshot(`
  ":root, :host {
    --radius-full: 99999px;
  }

  .rounded-full {
    border-radius: var(--radius-full);
  }"
`)

This allows anyone who wants --radius-full to be a CSS variable to simply define it in their theme:

@theme {
  /* Make `--radius-full` a CSS variable without the utility generating two CSS classes */
  --radius-full: calc(infinity * 1px);
}

The idea is to extend this pattern across all functional utilities that also have static utilities that can collide with the namespace. This gives users more control over what they want as CSS variables when the defaults don't work for them, allowing them to resolve #16639 and #15115 in user space.

You may now find yourself thinking "but Philipp, why would someone want to be able to overwrite --animate-none. none surely always will mean no animation" and I would agree but it's already possible right now anyways so this is not a new behavior! This PR just cleans up the generated output.

philipp-spiess · 2025-09-09T15:09:02Z

Going to retire this for now

philipp-spiess · 2025-09-09T15:16:59Z

Actually still like this better than the alternatives. Let me see if an LLM can figure out all utilities without too much hassle.

RobinMalfait

I like it! Got a few questions and suggestions related to.. suggestions to simplify this a bit more.

RobinMalfait · 2025-09-10T12:30:20Z

packages/tailwindcss/src/utilities.test.ts

+    }
+
+    .col-start-auto {
+      grid-column: var(--grid-column-start-auto);


Interesting, this should be solved by #18907

RobinMalfait · 2025-09-10T12:33:39Z

packages/tailwindcss/src/utilities.test.ts

-      border-top-left-radius: 3.40282e38px;
-      border-top-right-radius: 3.40282e38px;
      border-top-left-radius: var(--radius-full);
      border-top-right-radius: var(--radius-full);


RobinMalfait · 2025-09-10T12:37:24Z

packages/tailwindcss/src/utilities.test.ts

+    .backdrop-blur-none {
+      --tw-backdrop-blur: blur(var(--backdrop-blur-none));
+      -webkit-backdrop-filter: var(--tw-backdrop-blur, ) var(--tw-backdrop-brightness, ) var(--tw-backdrop-contrast, ) var(--tw-backdrop-grayscale, ) var(--tw-backdrop-hue-rotate, ) var(--tw-backdrop-invert, ) var(--tw-backdrop-opacity, ) var(--tw-backdrop-saturate, ) var(--tw-backdrop-sepia, );
+      backdrop-filter: var(--tw-backdrop-blur, ) var(--tw-backdrop-brightness, ) var(--tw-backdrop-contrast, ) var(--tw-backdrop-grayscale, ) var(--tw-backdrop-hue-rotate, ) var(--tw-backdrop-invert, ) var(--tw-backdrop-opacity, ) var(--tw-backdrop-saturate, ) var(--tw-backdrop-sepia, );
+    }


Not related to this PR, but this output is crazy and made me think about something... I wonder if we can be a bit smarter here and optimize the output based on what you used.

So if you only use blur that we get rid of all the other variables used here.

If you have a utility that sets some backdrop opacity, or if we detect that --tw-backdrop-saturate is used, that we start including it in the output.

Food for thought 🤔

Hmm, interesting, but unfortunately would be a breaking change if people used runtime to define these variables right? 🤔

It would, but we also consider those --tw-* variables as private-ish anyway 🤷‍♂️

Yeah fair I guess 👍

I think this would be the first case of the presence of other utilities affecting the generated CSS for different utilities. Would also need to invalidate the internal AST caches for those utilities.

Yeah it does feel like a bit of a stretch, especially in regard to the changes in this PR.

@thecrypticace Yep but I like to think about it in a different way. Similar to how we define CSS variables and remove them when they are not used, or similar to how we only emit CSS for used utilities today.

The CSS variables are also only emitted based on the presence of other utilities (except for @theme static).

If you think about it like this, then it could be part of the optimization step where we remove certain @property at-rules or used var(--tw-*) in declarations. Might not be as easy to generalize this but it wouldn't touch the cached AST.

Yeah it does feel like a bit of a stretch, especially in regard to the changes in this PR.

Hence the Not related to this PR part, just noticed it while looking over the diff 😅

So definitely something that should not be part of this PR. Please ignore all aforementioned comments 🙈.

packages/tailwindcss/src/utilities.ts

RobinMalfait · 2025-09-10T12:44:04Z

packages/tailwindcss/src/utilities.ts

+    staticValues: {
+      center: [decl('transform-origin', 'center')],
+      top: [decl('transform-origin', 'top')],
+      'top-right': [decl('transform-origin', '100% 0')],
+      right: [decl('transform-origin', '100%')],
+      'bottom-right': [decl('transform-origin', '100% 100%')],
+      bottom: [decl('transform-origin', 'bottom')],
+      'bottom-left': [decl('transform-origin', '0 100%')],
+      left: [decl('transform-origin', '0')],
+      'top-left': [decl('transform-origin', '0 0')],
+    },


I almost wish this was a Map so all the keys would have quotes around them 😂

RobinMalfait · 2025-09-10T12:48:57Z

packages/tailwindcss/src/utilities.ts

+  // Ensure discoverability for `col-auto` after converting to fallback
+  suggest('col', () => [{ values: ['auto'], valueThemeKeys: ['--grid-column'] }])


I wonder if we can make these suggestions more automatic as part of the functionalUtility helper because we know the root, we know the values (keys of staticValues) and we know the valueThemeKeys.

Should simplify some of the additional code and ensure everything is in sync when we update some static values. Thoughts?

Can't provide a suggestion to code that didn't change (thanks GitHub!), but something like this should work I think:

if (desc.staticValues) { let values = Object.keys(desc.staticValues) suggest(classRoot, () => [{ values, valueThemeKeys: desc.themeKeys ?? [] }]) }

at the end of the functionalUtility function

Hmmmm, right now though, the functionalUtility does not provide any suggestions on its own and I think that's a good thing: If we ever decide to double-down on the browser build, we'd want a convenient way to compile the suggestions away and then this current setup will become useful. That said for the previous staticUtility() helper, suggestions are provided by default so it wasn't very consistent to begin with so I'm fine with either approach.

right now though, the functionalUtility does not provide any suggestions on its own

What do you mean by this exactly? We do have this already:

tailwindcss/packages/tailwindcss/src/utilities.ts

Lines 449 to 456 in 340b59d

suggest(classRoot, () => [

{

supportsNegative: desc.supportsNegative,

valueThemeKeys: desc.themeKeys ?? [],

hasDefaultValue: desc.defaultValue !== undefined && desc.defaultValue !== null,

supportsFractions: desc.supportsFractions,

},

])

Which is part of the functionalUtility function when being called.

Oh I see, interesting! Then I guess I am wrong and it should just work. no idea why namespaces keys aren't added automatically then too, though 🤔

@RobinMalfait updated!

RobinMalfait

Few more things that can be deleted with that latest change.

A few things after this:

Need to update tests because of the fix in #18907
Needs a changelog entry

packages/tailwindcss/src/utilities.ts

…ppress generation when namespaced; keep IntelliSense unchanged; rename fallbacks->staticValues; add targeted override tests

Co-authored-by: Robin Malfait <[email protected]>

…stions non-negative and merge with existing groups

This comment was marked as outdated.

Sign in to view

philipp-spiess closed this Sep 9, 2025

philipp-spiess reopened this Sep 9, 2025

philipp-spiess force-pushed the feat/allow-overwriting-static-utilities branch from b3e8e4d to 531201b Compare September 10, 2025 12:13

philipp-spiess marked this pull request as ready for review September 10, 2025 12:17

philipp-spiess requested a review from a team as a code owner September 10, 2025 12:17

RobinMalfait reviewed Sep 10, 2025

View reviewed changes

philipp-spiess force-pushed the feat/allow-overwriting-static-utilities branch from a846126 to c6ad58f Compare September 11, 2025 10:02

philipp-spiess and others added 8 commits September 11, 2025 12:03

Proposal: Allow overwriting static utilities that have a namespace

a4714eb

utilities: convert conflicting statics to functional staticValues; su…

2f04408

…ppress generation when namespaced; keep IntelliSense unchanged; rename fallbacks->staticValues; add targeted override tests

Update packages/tailwindcss/src/utilities.ts

a8409d5

Co-authored-by: Robin Malfait <[email protected]>

utilities: auto-suggest staticValues in functionalUtility; keep sugge…

3037a11

…stions non-negative and merge with existing groups

Move suggestion into utility helper

9e274d6

Run formatter

ad45c77

Cleanup & changelog entry

69b94cd

Cleanups

88b4541

philipp-spiess force-pushed the feat/allow-overwriting-static-utilities branch from c6ad58f to 88b4541 Compare September 11, 2025 10:06

RobinMalfait approved these changes Sep 11, 2025

View reviewed changes

philipp-spiess merged commit d1fd645 into main Sep 11, 2025
7 checks passed

philipp-spiess deleted the feat/allow-overwriting-static-utilities branch September 11, 2025 10:21

This was referenced Sep 11, 2025

Add --radius-full variable #17002

Closed

[v4] --radius-full is not available as a variable #15115

Closed

		// Ensure discoverability for `col-auto` after converting to fallback
		suggest('col', () => [{ values: ['auto'], valueThemeKeys: ['--grid-column'] }])

	suggest(classRoot, () => [
	{
	supportsNegative: desc.supportsNegative,
	valueThemeKeys: desc.themeKeys ?? [],
	hasDefaultValue: desc.defaultValue !== undefined && desc.defaultValue !== null,
	supportsFractions: desc.supportsFractions,
	},
	])

Uh oh!

Proposal: Allow overwriting static utilities that have a namespace #18056

Proposal: Allow overwriting static utilities that have a namespace #18056

Uh oh!

Conversation

philipp-spiess commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

philipp-spiess commented Sep 9, 2025

Uh oh!

philipp-spiess commented Sep 9, 2025

Uh oh!

RobinMalfait left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RobinMalfait Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RobinMalfait Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RobinMalfait left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

philipp-spiess commented May 16, 2025 •

edited

Loading

RobinMalfait Sep 10, 2025 •

edited

Loading

RobinMalfait Sep 10, 2025 •

edited

Loading